<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>StringGetPos</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StringGetPos</h1>

<p>Retrieves the position of the specified substring within a string.</p>

<pre class="Syntax">StringGetPos, OutputVar, InputVar, SearchText [, L#|R#, Offset]
Position := <a href="../Functions.htm#InStr">InStr</a>(Haystack, Needle [, CaseSensitive?, StartingPos]) <em>; See the <a href="../Functions.htm#InStr">InStr() function</a> for details.</em></pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the retrieved position relative to the first character of <em>InputVar</em>. Position 0 is the first character for StringGetPos and position 1 is the first character for <a href="../Functions.htm#InStr">InStr()</a>.</p></dd>

  <dt>InputVar</dt>
  <dd><p>The name of the input variable, whose contents will be searched. Do not enclose the name in percent signs unless you want the <em>contents</em> of the variable to be used as the name.</p></dd>

  <dt>SearchText</dt>
  <dd><p>The string to search for. Matching is not case sensitive unless <a href="StringCaseSense.htm">StringCaseSense</a> has been turned on.</p></dd>

  <dt>L#|R#</dt>
  <dd><p>This affects which occurrence will be found if <em>SearchText</em> occurs more than once within <em>InputVar</em>. If this parameter is omitted, <em>InputVar</em> will be searched starting from the left for the first match. If this parameter is 1 or the letter R, the search will start looking at the right side of <em>InputVar</em> and will continue leftward until the first match is found.</p>
      <p>To find a match other than the first, specify the letter L or R followed by the number of the occurrence. For example, to find the fourth occurrence from the right, specify r4. Note: If the number is less than or equal to zero, no match will be found.</p></dd>

  <dt>Offset</dt>
  <dd><p>The number of characters on the leftmost or rightmost side (depending on the parameter above) to skip over. If omitted, the default is 0. For example, the following would start searching at the tenth character from the left: <code>StringGetPos, OutputVar, InputVar, abc, , 9</code>. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>.</p></dd>

</dl>

<h3>ErrorLevel</h3>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if the specified occurrence of <em>SearchText</em> could not be found within <em>InputVar</em>, or 0 otherwise.</p>
<h3>Remarks</h3>
<p>Unlike <a href="StringMid.htm">StringMid</a> and <a href="../Functions.htm#InStr">InStr()</a>, 0 is defined as the position of the first character for StringGetPos.</p>
<p>The retrieved position is always relative to the first character of <em>InputVar</em>, regardless of whether <em>L#|R#</em> and/or <em>Offset</em> are specified. For example, if the string &quot;abc&quot; is found in 123abc789, its reported position will always be 3 regardless of the method by which it was found.</p>
<p>If the specified occurrence of <em>SearchText</em> does not exist within <em>InputVar</em>, <em>OutputVar</em> will be set to -1 and <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to 1.</p>
<p>Use <a href="SplitPath.htm">SplitPath</a> to more easily parse a file path into its directory, filename, and extension.</p>
<p>The built-in variables <a href="../Variables.htm">%A_Space%</a> and <a href="../Variables.htm">%A_Tab%</a> contain a single space and a single tab character, respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of <em>SearchText</em>.</p>
<h3>Related</h3>
<p><a href="../Functions.htm#InStr">InStr()</a>, <a href="RegExMatch.htm">RegExMatch()</a>, <a href="IfInString.htm">IfInString</a>, <a href="IfIn.htm">if var in/contains MatchList</a>, <a href="StringCaseSense.htm">StringCaseSense</a>, <a href="StringReplace.htm">StringReplace</a>, <a href="SplitPath.htm">SplitPath</a>, <a href="StringLeft.htm">StringLeft</a>, <a href="StringLeft.htm">StringRight</a>, <a href="StringMid.htm">StringMid</a>, <a href="StringTrimLeft.htm">StringTrimLeft</a>, <a href="StringTrimLeft.htm">StringTrimRight</a>, <a href="StringLen.htm">StringLen</a>, <a href="StringLower.htm">StringLower</a>, <a href="StringLower.htm">StringUpper</a>, <a href="IfIs.htm">if var is type</a></p>
<h3>Examples</h3>
<pre class="NoIndent">Haystack = abcdefghijklmnopqrs
Needle = def
StringGetPos, pos, Haystack, %Needle%
if pos &gt;= 0
    MsgBox, The string was found at position %pos%.</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example #2:
; Divides up the full path name of a file into components.
; Note that it would be much easier to use <a href="StringSplit.htm">StringSplit</a> or a
; <a href="LoopParse.htm">parsing loop</a> to do this, so the below is just for illustration.</em>
FileSelectFile, file, , , Pick a filename in a deeply nested folder:
if file &lt;&gt;
{
    StringLen, pos_prev, file
    pos_prev += 1 <em>; Adjust to be the position after the last char.</em>
    Loop
    {
        <em>; Search from the right for the Nth occurrence:</em>
        <strong>StringGetPos</strong>, pos, file, \, R%A_Index%
        if ErrorLevel
            break
        length := pos_prev - pos - 1
        pos_prev := pos
        pos += 2  <em>; Adjust for use with StringMid.</em>
        StringMid, path_component, file, %pos%, %length%
        MsgBox Path component #%a_index% (from the right) is:`n%path_component%
    }
}</pre>

</body>
</html>
